Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Configuring Sequence Grabber Components

Sequence grabber components provide a number of functions that allow you to establish the environment for grabbing or previewing digitized data. Before you can start a record or a preview operation, you must initialize the sequence grabber component, establish the channels that will be used, define the display environment for the operation, and determine the optimum screen position for the sequence grabber. In addition, if you are performing a record operation, you must define a destination movie file. This section describes the sequence grabber component functions that allow you to perform these tasks.

You can use the SGInitialize function to initialize a sequence grabber component. Before you can call this function, you must establish a connection to the sequence grabber by calling the Component Manager's OpenDefaultComponent or OpenComponent function.

The SGNewChannel function allows you to create channels for the sequence grabber for an operation. You can use the SGNewChannelFromComponent function to create a new channel using a specified channel component. Use the SGDisposeChannel function to dispose of those channels that you are no longer using.

You can use the SGGetIndChannel function to retrieve information about the channels that are currently in use by the sequence grabber.

You can use the SGSetGWorld and SGGetGWorld functions to establish the display environment for the sequence grabber. These functions affect only those channels that work with data that has visual information.

The SGSetDataOutput and SGGetDataOutput functions allow you to identify the movie file that is currently assigned to the sequence grabber. You only use these functions when you are performing a record operation.

The SGSetDataProc function allows you to assign a data function to a channel. The sequence grabber calls your data function whenever it writes movie data to the output file.

The SGGetAlignmentProc function allows you to determine a sequence grabber's optimum screen position to ensure the best performance and appearance.

SGInitialize

The SGInitialize function allows you to initialize the sequence grabber component. Before you can call this function you must establish a connection to the sequence grabber component. Use the Component Manager's OpenDefaultComponent or OpenComponent function to establish a component connection.

pascal ComponentResult SGInitialize (SeqGrabComponent s);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.

DESCRIPTION

You must call the SGInitialize function before you call any other sequence grabber component functions. If this function returns a nonzero result code, you should close your connection to the sequence grabber component.

RESULT CODES

Memory Manager errors

SGSetDataOutput

The SGSetDataOutput function allows you to specify the movie file for a record operation and to specify other options that govern the operation. The sequence grabber component stores the data that is obtained during the record operation as a QuickTime movie in this file. This function also allows you to control some aspects of the record operation, which are related to output, by specifying control flags. These flags are discussed in the function description that follows.

pascal ComponentResult SGSetDataOutput (SeqGrabComponent s,
                                          const FSSpec *movieFile,
                                          long whereFlags);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
movieFile
Contains a pointer to the movie file for this record operation.
whereFlags
Contains flags that control the record operation. The following flags are defined by the SeqGrabDataOutputEnum data type; you must set either the seqGrabToDisk flag or the seqGrabToMemory flag to 1 (set unused flags to 0).
seqGrabToDisk
Instructs the sequence grabber component to write the recorded data to a QuickTime movie in the movie file specified by the movieFile parameter. If you set this flag to 1, the sequence grabber writes the data to the file as the data is recorded. Set this flag to 0 if you set the seqGrabToMemory flag to 1 (only one of these two flags may be set to 1).
seqGrabToMemory
Instructs the sequence grabber component to store the recorded data in memory until the recording process is complete. The sequence grabber then writes the recorded data to the movie file specified by the movieFile parameter. This technique provides better performance than recording directly to the movie file, but it limits the amount of data you can record. Set this flag to 1 to record to memory. Set this flag to 0 if you set the seqGrabToDisk flag to 1 (only one of these two flags may be set to 1).
seqGrabDontUseTempMemory
Prevents the sequence grabber component from using temporary memory during the record operation. By default, the sequence grabber component and its channel components use as much temporary memory as necessary to perform the record operation. Set this flag to 1 to prevent the sequence grabber component and its channel components from using temporary memory.
seqGrabAppendToFile
Directs the sequence grabber component to add the recorded data to the data fork of the movie file specified by the movieFile parameter. By default, the sequence grabber component deletes the movie file and creates a new file containing one movie and the corresponding movie resource. Set this flag to 1 to cause the sequence grabber component to append the recorded data to the data fork of the movie file and create a new movie resource in that file.
seqGrabDontAddMovieResource
Prevents the sequence grabber component from adding the new movie resource to the movie file specified by the movieFile parameter. By default, the sequence grabber component creates a new movie resource and adds that resource to the movie file. Set this flag to 1 to prevent the sequence grabber component from adding the movie resource to the movie file. You are then responsible for adding the resource to a file, if you so desire.
seqGrabDontMakeMovie
Prevents the sequence grabber component from creating a movie. By default, the sequence grabber component creates a new movie resource and adds the captured data to that movie. If you set this flag to 1, the sequence grabber still calls your data function, but does not write any data to the movie file.

DESCRIPTION

If you are performing a preview operation, you do not need to use the SGSetDataOutput function.

RESULT CODES

notEnoughMemoryToGrab

-9403

Insufficient memory for record operation

notEnoughDiskSpaceToGrab

-9404

Insufficient disk space for record operation

File Manager errors Memory Manager errors

SGGetDataOutput

The SGGetDataOutput function allows you to determine the movie file that is currently assigned to a sequence grabber component and the control flags that would govern a record operation.

pascal ComponentResult SGGetDataOutput (SeqGrabComponent s,
                                          FSSpec *movieFile,
                                          long *whereFlags);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
movieFile
Contains a pointer to a file system specification record that is to receive information about the movie file for this record operation.
whereFlags
Contains a pointer to a long integer that is to receive flags that control the record operation. The following flags are defined (unused flags are set to 0):
seqGrabToDisk
Instructs the sequence grabber component to write the recorded data to a QuickTime movie in the movie file specified by the movieFile parameter. If this flag is set to 1, the sequence grabber writes the data to the file as the data is recorded.
seqGrabToMemory
Instructs the sequence grabber component to store the recorded data in memory until the recording process is complete. The sequence grabber then writes the recorded data to the movie file specified by the movieFile parameter. This technique provides better performance than recording directly to the movie file, but it limits the amount of data you can record. If this flag is set to 1, the sequence grabber component is recording to memory.
seqGrabDontUseTempMemory
Prevents the sequence grabber component from using temporary memory during the record operation. By default, the sequence grabber component and its channel components use as much temporary memory as necessary to perform the record operation. If this flag is set to 1, the sequence grabber component and its channel components do not use temporary memory.
seqGrabAppendToFile
Directs the sequence grabber component to add the recorded data to the data fork of the movie file specified by the movieFile parameter. By default, the sequence grabber component deletes the movie file and creates a new file containing one movie and its movie resource. If this flag is set to 1, the sequence grabber component appends the recorded data to the data fork of the movie file and creates a new movie resource in that file.
seqGrabDontAddMovieResource
Prevents the sequence grabber component from adding the new movie resource to the movie file specified by the movieFile parameter. By default, the sequence grabber component creates a new movie resource and adds that resource to the movie file. If this flag is set to 1, the sequence grabber component does not add the movie resource to the movie file. You are then responsible for adding the resource to a file, if you so desire.
seqGrabDontMakeMovie
Prevents the sequence grabber component from creating a movie. By default, the sequence grabber component creates a new movie resource and adds the captured data to that movie. If this flag is set to 1, the sequence grabber still calls your data function, but does not write any data to the movie file.

DESCRIPTION

You set these characteristics by calling the SGSetDataOutput function, which is described in the previous section. If you have not set these characteristics before calling the SGGetDataOutput function, the returned data is meaningless.

SGSetGWorld

The SGSetGWorld function allows you to establish the graphics port and device for a sequence grabber component. The sequence grabber component displays the recorded or previewed data in this graphics world.

pascal ComponentResult SGSetGWorld (SeqGrabComponent s,
                                         CGrafPtr gp, GDHandle gd);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
gp
Specifies the destination graphics port. The specified graphics port must be a color graphics port. Set this parameter to nil to use the current graphics port.
gd
Specifies the destination graphics device. Set this parameter to nil to use the current device. If the gp parameter specifies a graphics world, set this parameter to nil to use that graphics world's graphics device.

DESCRIPTION

You must call this function if you are working with any channels that collect visual data. If you are working only with data that has no visual representation, you do not need to call this function. The sequence grabber component performs this operation implicitly when you call the SGInitialize function (described on SGInitialize ), and the component uses your application's current graphics port.

You cannot call this function during a record or preview operation or after you have prepared the sequence grabber component for a record or preview operation (by calling the SGPrepare function, which is described on SGPrepare ).

The window in which the sequence grabber is to draw video frames as defined by SGSetGWorld must be visible before you call the SGPrepare function. Otherwise, the sequence grabber does not display the frames properly. For details, see the discussion of SGPrepare beginning on SGPrepare .

RESULT CODE

cantDoThatInCurrentMode

-9402

Request invalid in current mode

SGGetGWorld

The SGGetGWorld function allows you to determine the graphics port and device for a sequence grabber component.

pascal ComponentResult SGGetGWorld (SeqGrabComponent s,
                                          CGrafPtr *gp, GDHandle *gd);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
gp
Contains a pointer to a location that is to receive a pointer to the destination graphics port. Set this parameter to nil if you are not interested in this information.
gd
Contains a pointer to a location that is to receive a handle to the destination graphics device. Set this parameter to nil if you are not interested in this information.

DESCRIPTION

The sequence grabber component displays the recorded or previewed data in this graphics world.

SEE ALSO

You can establish the graphics port and device for a sequence grabber component by calling the SGSetGWorld function, which is described in the previous section.

SGNewChannel

The SGNewChannel function creates a sequence grabber channel and assigns a channel component to the channel. The channel component is responsible for providing digitized data to the sequence grabber component. You specify the type of channel component to be added to the sequence grabber component.

pascal ComponentResult SGNewChannel (SeqGrabComponent s,
                                          OSType channelType,
                                          SGChannel *ref);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
channelType
Specifies the type of channel to open. This value corresponds to the component subtype value of the channel component. The following values are valid:
VideoMediaType
Video channel
SoundMediaType
Sound channel
ref
Contains a pointer to the frameChannel field in the sequence grabber information structure that is to receive a reference to the channel that is added to the sequence grabber component. If the sequence grabber component successfully locates and connects to an appropriate channel component, the sequence grabber component returns a reference to the channel component into the field referred to by this parameter. If the sequence grabber component cannot open a connection, it sets the result code to a nonzero value.

DESCRIPTION

The sequence grabber component locates, and attempts to connect to, an appropriate channel component. If the sequence grabber component cannot locate or connect to a channel component, it returns a nonzero result code.

RESULT CODES

couldntGetRequiredComponent

-9405

Component not found

Memory Manager errors

SEE ALSO

When you are done with the sequence grabber component, you can dispose of the channels you have used by calling the SGDisposeChannel function, which is described on SGDisposeChannel . However, when you close the sequence grabber component, it automatically disposes of all its channels, so this function is usually unnecessary.

If you want to use a specific channel component, you may use the SGNewChannelFromComponent function, which is described next.

SGNewChannelFromComponent

The SGNewChannelFromComponent function creates a sequence grabber channel and assigns a channel component to the channel. The channel component is responsible for providing digitized data to the sequence grabber component. You specify the channel component to be used.

pascal ComponentResult SGNewChannelFromComponent
                                          (SeqGrabComponent s, SGChannel *newChannel,
                                          Component sgChannelComponent);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
newChannel
Contains a pointer to a channel component that is to receive a reference to the channel that is added to the sequence grabber component. If the sequence grabber component successfully locates and connects to the specified channel component, the sequence grabber component returns a reference to the channel component into the field referred to by this parameter. If the sequence grabber component cannot open a connection, it sets the result code to a nonzero value.
sgChannelComponent
Identifies the channel component to use. You supply a component ID value to the sequence grabber. The sequence grabber then opens a connection to that channel component and returns your connection ID in the field specified by the newChannel parameter. You may obtain a component ID value by calling the Component Manager's FindNextComponent function.

DESCRIPTION

The sequence grabber component locates and connects to the specified channel component. If the sequence grabber component cannot locate or connect to the channel component, it returns a nonzero result code.

This function is similar to the SGNewChannel function, except that this function allows you to specify a particular component rather than just a component subtype value. Use this function if you want to connect to a specific component.

RESULT CODES

couldntGetRequiredComponent

-9405

Component not found

Memory Manager errors

SEE ALSO

You may also use the SGNewChannel function to establish a new channel. That function requires only a component subtype value, and is described on SGNewChannel .

When you are done with the sequence grabber component, you can dispose of the channels you have used by calling the SGDisposeChannel function, which is described on SGDisposeChannel .

SGGetIndChannel

The SGGetIndChannel function allows you to collect information about all of the channel components currently in use by a sequence grabber component.

pascal ComponentResult SGGetIndChannel (SeqGrabComponent s,
                                          short index,
                                          SGChannel *ref,
                                          OSType *chanType);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
index
Specifies an index value. This value identifies the channel to be queried. The first channel has an index value of 1.
ref
Contains a pointer to a field to receive a value identifying your connection to the channel. If you do not want to receive this information, set this parameter to nil .
chanType
Contains a pointer to a field to receive the channel's subtype value. This value indicates the media type supported by the channel component. The following values are valid:
VideoMediaType
Video channel
SoundMediaType
Sound channel
If you do not want to receive this information, set this parameter to nil .

DESCRIPTION

You may use the SGGetIndChannel function to retrieve information about each of the channel components currently in use by a sequence grabber component. You identify the channel in which you are interested by specifying an index value. These index values start at 1 and increase sequentially; each channel has its own index value.

RESULT CODE

paramErr

-50

Component not found

SGDisposeChannel

The SGDisposeChannel function removes a channel from a sequence grabber component.

pascal ComponentResult SGDisposeChannel
                                         (SeqGrabComponent s, SGChannel c);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
c
Specifies the reference that identifies the channel you want to close. You obtain this reference from the SGNewChannel function, described in the previous section.

DESCRIPTION

You can use this function to remove a channel that you are no longer using. However, you cannot dispose of a channel that is currently active--if you are recording or previewing data, this function returns a nonzero result code.

RESULT CODE

badSGChannel

-9406

Invalid channel specified

SEE ALSO

The sequence grabber component automatically disposes of any open channels when you close your connection to the component, so you do not need to call this function prior to calling the Component Manager's CloseComponent function.

SGSetDataProc

The SGSetDataProc function allows you to specify a data function for use by the sequence grabber. Whenever any channel assigned to the sequence grabber writes data, your data function is called as well. Your data function may then write the data to another destination.

pascal ComponentResult SGSetDataProc (SeqGrabComponent s,
                                         SGDataUPP proc,
                                         long refCon);
s
Identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
proc
Contains a pointer to your data function. To remove your data function, set this parameter to nil . The interface that your data function must support is described in "Application-Defined Functions," .
refCon
Contains a reference constant. The sequence grabber provides this value to your data function.

DESCRIPTION

Your application may use the SGSetDataProc function to assign a data function to a sequence grabber. The sequence grabber calls your data function whenever any channel component writes data to the destination movie. You may use your data function to store the digitized data in some format other than a QuickTime movie.

SEE ALSO

You can instruct the sequence grabber not to write its data to a QuickTime movie by calling the SGSetDataOutput function and setting the seqGrabDontMakeMovie flag to 1. This can save processing time in cases where you do not want to create a movie. This function is discussed beginning on SGSetDataOutput .

SGGetAlignmentProc

The SGGetAlignmentProc function allows you to obtain information about the best screen positions for a sequence grabber's video image in terms of appearance and maximum performance.

pascal ComponentResult SGGetAlignmentProc (SeqGrabComponent s,
                                         ICMAlignmentProcRecordPtr alignmentProc);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
alignmentProc
Contains a pointer to an Image Compression Manager alignment function structure. The sequence grabber places its alignment information into this structure.

DESCRIPTION

You may use the SGGetAlignmentProc function to retrieve information about the best screen positions for the sequence grabber's window. The sequence grabber returns information that can be used by the Image Compression Manager's alignment functions (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about these functions). By using this alignment information, you can place the sequence grabber's window in a position that allows for optimal display performance.

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next